Mapping branches

This section describes what administrators need in order to map branches to streams.

Mapping overview

A GitCentric administrator uses the GitCentric GUI (and optionally the GitCentric CLI commands) to configure the mapping between Git branches and AccuRev streams. A Git repository (repo) is associated with a single AccuRev Server, and with an AccuRev username (the service account) for performing GitCentric administrative tasks. Once this association is defined, a GitCentric administrator can proceed to map Git repo branches to AccuRev streams on that server. The directory within a stream that is mapped to a Git branch is called the mount point.

After the mapping has been done, the GitCentric bridge web application uses triggers to automatically keep the Git repo and the AccuRev depot in sync, while the GitCentric GUI gives you the ability to create repos, map branches to streams, set ACLs, etc.

You can have multiple GitCentric AccuRev user accounts:

  • Administrative users who interactively log into the GitCentric GUI (and any related AccuRev Servers), for manual administrative tasks.
  • Service account users, accessed internally by the GitCentric bridge, for automatically syncing the Git repos and their mapped AccuRev streams

Service account users must be defined (either as an individual user, or as a group) in the AccuRev Server acserver.cnf file(s), using the ASSIGN_USER_PRIVILEGE setting in AccuRev 5.4 or later.

Note: Best practice is to assign this to a group so that different members of the group can have different access rights. For example, one member of the group might be from a remote organization with different access rights than another member of the group.

The syntax for the entry in acserver.cnf is 

ASSIGN_USER_PRIVILEGE = <user_or_group_name>

If you specify multiple ASSIGN_USER_PRIVILEGE settings, only the first one is honored.

Back to top

Basic rules

Regardless of how many Git repositories or AccuRev Servers you configure, when you associate a repo with a server, you map them at the branch and stream level:

A Git branch is mapped to an AccuRev stream. Follow these rules:

  • You can map multiple Git branches (and multiple Git repositories) to a single AccuRev stream.
  • You can map a Git branch to any directory within an AccuRev stream.
  • You cannot map a Git branch to multiple AccuRev streams.
  • You cannot map a Git branch to the root stream in an AccuRev depot. (If you need to do this, simply create a new stream off of the root, and then map to that.)

Back to top

Mapped behavior

If you push a file to the repository and it would require merging with the version of the file on the mapped AccuRev stream, GitCentric cancels the push and informs the user that he or she must pull the latest changes, merge and retry the push, the same way Git always handles these situations.

When you first map a Git branch to an AccuRev stream, you can specify whether the files in Git or on AccuRev take precedence.

Since AccuRev streams inherit versions from their backing streams, it is important to remember that if any automatically be pushed to the repo from AccuRev.

Back to top

Best practice for keeping merges and promotes in sync

We recommend that you merge into the child branch first and then fast forward merge the parent branch. If you merge into the child branch first, AccuRev will reflect this by performing a promote from the child stream to the parent stream. However, if you merge into the parent branch first, AccuRev will achieve the desired zero default group state by performing an AccuRev purge on the child stream.

The Git commands for merging into the child branch are:

git checkout C, git merge P, git checkout P, git merge C (This will be a fast-forward merge. Existing merge commit will be reused.), and git push.

Back to top

AccuRev replica server restriction

If your AccuRev installation has one or more replica servers, you should always try to associate GitCentric with the AccuRev master (if possible), and not a replica. Even if your GitCentric installation is physically located in close proximity to a replica server, you should try to configure GitCentric to work with the remote master AccuRev Server, not the geographically closer replica server. (This may not be possible if your installation has implemented firewalls and VPN or some other kind of security that prevents you from communicating directly with a remote master server.)

Back to top

Mapping multiple repositories to a single stream

This section describes the scenarios for mapping multiple repositories to a single stream. There are two primary reasons for mapping two different Git repositories to the same AccuRev stream: project-based and security-based.

In a project-based scenario, you map the same stream with different mounting points.

In this case, you might have two different parts of a product in two different directory structures in the same stream, such as a GUI development tree and a database development tree. In the Git environment, you could have the GUI work being done in one repository and the database work being done in another.

By mapping the branches in these repositories to the correct mount points in the same stream, you can keep the work separate. (Keeping the branch names consistent across repos will be helpful if you need to make branch-mapping changes en masse using the children-of option in the SSH config-branch CLI command.)

In a security-based scenario, you map the same stream and mount points, with different service accounts.

In this case, you could have two different sets of users with different access privileges accessing the same files. Privileged Git developers in corporate headquarters could have one repo mapped to the mount point with one service account having “lenient” AccuRev ACLs. Less privileged off-shore contract developers could have a different repo mapped to the same mount point with a different service account having much more restrictive AccuRev ACLs. For more information about ACLs and security, see Security configurations.

Also, by mapping branches from different repos to a single AccuRev stream, you can automate the process of updating repos with changes: when a change gets pushed to a repo that is mapped to an AccuRev stream, that change gets propagated to all other branches that are mapped to that stream (assuming that the AccuRev ACLs allow a repo to “see” the changed file).

Back to top

See also: